feat: Add Pagination for server requests by denniskawurek · Pull Request #140 · modelcontextprotocol/java-sdk

denniskawurek · 2025-04-10T20:22:29Z

Adds the Pagination feature to the prompts/list feature to fulfil the specification.

Motivation and Context

This adds the Pagination feature to the prompts/list feature as described in the specification.

To make this possible mainly two changes are made:

The logic for cursor handling is added.
Handling for invalid parameters (MCP error code -32602 (Invalid params)) is added to the McpServerSession.

Decisions made:

For now the cursor is the integer value of the start index encoded as a base64 string.
The page size is set to 10.
When parameters are found to be invalid the newly introduced McpParamsValidationError is returned to handle it properly in the McpServerSession.

If this change is ok, I'm happy to create a follow-up PR for the other MCP features. Maybe some parts of the cursor handling can be moved out to separate methods.

How Has This Been Tested?

Integration tests are added for the prompts/list feature.

Types of changes

New feature (non-breaking change which adds functionality)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Resolves #967

chemicL

Thank you for the contribution! It is a great start, would you like to take this further and unify the logic for other listing requests?

denniskawurek · 2025-04-24T10:41:37Z

Hi,

thanks for your review and your feedback!

Thank you for the contribution! It is a great start, would you like to take this further and unify the logic for other listing requests?

Yes I will do this. I should be able to update the pull request by the end of the week.

denniskawurek · 2025-04-28T17:16:05Z

I did another push with small changes in the commit title and message and have also changed a few comments and names in tests. No business logic was affected.

Adds the Pagination feature as described in the specification for prompts, resources, resource templates and tools. To make this possible mainly two changes are made: 1. The logic for cursor handling is added. 2. Handling for invalid parameters (MCP error code `-32602 (Invalid params)`) is added to the `McpServerSession`. For now the cursor is the base64 encoded start index of the next page and the hash value of the collection at time of computing. The page size is set to 10. When parameters are found to be invalid the newly introduced `McpParamsValidationError` is returned to handle it properly in the `McpServerSession`.

pantanurag555 · 2025-06-23T23:35:49Z

@denniskawurek Is this change still being worked on? I am making some changes to handle pagination on the client side and just saw that the server side changes are yet to be merged. I can pick up the remaining work on this PR if you need some help.

denniskawurek · 2025-06-24T16:23:44Z

Hi @pantanurag555

I've just merged main into the branch, so that it's up to date, again.

Regarding your question I haven't started anything in regards of the client, yet.
The idea was here to have only the implementation for the server and implement the client in a separate commit/merge request, to keep the change as small as possible like it's stated in the contribution guidelines.
However that's the way I'd prefer to do.

Maybe @chemicL can give some information of the maintainer point of view and whether this change is interesting.

Regards
Dennis

denniskawurek · 2025-08-19T18:34:28Z

Looks like the test is flaky somehow. However, I'm not allowed to rerun the job.

lwilli · 2025-10-13T18:13:54Z

Hi, thanks for putting this work together. I am very interested in seeing PR merged as it's blocking some of my work right now. What needs to be done to move this along? Thanks in advance!

denniskawurek · 2026-05-17T18:01:36Z

Resolves #967

Kehrlann

Hey @denniskawurek , picking this up from #967

A few concerns here:

It's a breaking change ; we should default to non-paginated results
Page size should be configurable
We've introduced tool filtering as part of #1108 ; so now the view is request dependent. If that PR gets merged first, you'll need to adapt the pagination to happen after the filtering (shouldn't be too hard)

Kehrlann · 2026-08-26T12:54:43Z

+			var cursor = paginatedRequest != null ? paginatedRequest.cursor() : null;
+
+			var mapSize = this.tools.size();
+			var mapHash = this.tools.hashCode();


This is likely wrong across horizontally-scaled instances - hashCode hashes the *ToolSpecification, which contain handlers, and the hash of those will be tied to object identity.

Additionally, that's hashing a lot of things, including input and output schema strings, without ever caching them.

We should probably hash across keys (tool names), but I guess we have no guarantee of tool names being unique so there's something to do about this too

Kehrlann · 2026-08-26T12:58:45Z

+				var resultList = this.resources.values()
+					.stream()


I think the ordering is not guaranteed to be stable in a ConcurrentHashMap. I think in practice it's stable, BUT if you start adding elements dynamically and grow the underlying map, you may end up with different orders. I don't think it's a massive problem in this specific case.

If we do order by key as suggested in tools, we can sort the keys and get a stability guarantee (unless you modify the collection during a pagination run, but that's a corner case.)

Kehrlann · 2026-08-26T13:08:29Z

+	private BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, CallToolResult> buildCallToolRequestHandlerMock() {
+		var callResponse = McpSchema.CallToolResult.builder()
+			.addContent(McpSchema.TextContent.builder("CALL RESPONSE").build())
+			.build();
+
+		return (exchange, request) -> {
+			// perform a blocking call to a remote service
+			try {
+				HttpResponse<String> response = HttpClient.newHttpClient()
+					.send(HttpRequest.newBuilder()
+						.uri(URI.create(
+								"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+						.GET()
+						.build(), HttpResponse.BodyHandlers.ofString());
+				String responseBody = response.body();
+				assertThat(responseBody).isNotBlank();
+			}
+			catch (Exception e) {
+				e.printStackTrace();
+			}
+			return callResponse;
+		};
+	}


Is there a reason for reaching out to a remote service in tests? I'd rather avoid that and just return a result.

denniskawurek force-pushed the add-pagination branch 2 times, most recently from 4c05e1a to 8d48b93 Compare April 18, 2025 12:06

chemicL requested changes Apr 23, 2025

View reviewed changes

chemicL added the waiting for user Waiting for user feedback or more details label Apr 23, 2025

denniskawurek force-pushed the add-pagination branch 3 times, most recently from 3dce44d to 0c93c71 Compare April 26, 2025 14:52

denniskawurek requested a review from chemicL April 26, 2025 15:36

denniskawurek force-pushed the add-pagination branch from 0c93c71 to b02db82 Compare April 28, 2025 17:14

denniskawurek changed the title ~~feat: Add Pagination for requesting list of prompts~~ feat: Add Pagination for server requests Apr 29, 2025

denniskawurek force-pushed the add-pagination branch 3 times, most recently from 3718965 to 5f7bb9b Compare May 3, 2025 11:41

denniskawurek force-pushed the add-pagination branch from 5f7bb9b to 094088d Compare May 9, 2025 17:50

tzolov removed the waiting for user Waiting for user feedback or more details label May 12, 2025

Merge branch 'main' into add-pagination

317d674

denniskawurek added 5 commits July 29, 2025 21:52

Merge branch 'main' into add-pagination

2625932

chore: Apply formatter

bfc5e81

Merge remote-tracking branch 'upstream/main' into add-pagination

91a30a7

feat: Handle invalid cursor in streamable transport provider

1998f17

chore: Apply formatter

d366e25

denniskawurek mentioned this pull request Oct 11, 2025

Pagination is not working for the /tools/list API #615

Closed

Merge branch 'main' into add-pagination

4a95718

denniskawurek added 2 commits May 17, 2026 19:14

feat: Server handles pagination

e68bbd8

fix: Handle absent params

532929c

denniskawurek added 3 commits May 20, 2026 10:59

Merge branch 'main' into add-pagination

d3be706

Merge branch 'main' into add-pagination

b369c17

fix: Apply formatter and move ParameterizedTests

bb659cf

denniskawurek mentioned this pull request Jul 27, 2026

Server should handle paginated requests #967

Open

Kehrlann reviewed Aug 26, 2026

View reviewed changes

Kehrlann self-assigned this Aug 26, 2026

Kehrlann added enhancement New feature or request area/server P3 Nice to haves, rare edge cases waiting for user Waiting for user feedback or more details labels Aug 26, 2026

Uh oh!

Conversation

denniskawurek commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Types of changes

Checklist

Uh oh!

chemicL left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

denniskawurek commented Apr 24, 2025

Uh oh!

denniskawurek commented Apr 28, 2025

Uh oh!

pantanurag555 commented Jun 23, 2025

Uh oh!

denniskawurek commented Jun 24, 2025

Uh oh!

denniskawurek commented Aug 19, 2025

Uh oh!

lwilli commented Oct 13, 2025

Uh oh!

denniskawurek commented May 17, 2026

Uh oh!

Kehrlann left a comment

Choose a reason for hiding this comment

Uh oh!

Kehrlann Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Kehrlann Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Kehrlann Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

denniskawurek commented Apr 10, 2025 •

edited

Loading